.TH std::map::try_emplace 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::map::try_emplace \- std::map::try_emplace

.SH Synopsis
   template< class... Args >
   std::pair<iterator, bool> try_emplace( const Key& k, Args&&...     \fB(1)\fP \fI(since C++17)\fP
   args );
   template< class... Args >                                          \fB(2)\fP \fI(since C++17)\fP
   std::pair<iterator, bool> try_emplace( Key&& k, Args&&... args );
   template< class K, class... Args >                                 \fB(3)\fP (since C++26)
   std::pair<iterator, bool> try_emplace( K&& k, Args&&... args );
   template< class... Args >
   iterator try_emplace( const_iterator hint, const Key& k, Args&&... \fB(4)\fP \fI(since C++17)\fP
   args );
   template< class... Args >
   iterator try_emplace( const_iterator hint, Key&& k, Args&&... args \fB(5)\fP \fI(since C++17)\fP
   );
   template< class K, class... Args >
   iterator try_emplace( const_iterator hint, K&& k, Args&&... args   \fB(6)\fP (since C++26)
   );

   If a key equivalent to k already exists in the container, does nothing. Otherwise,
   inserts a new element into the container with key k and value constructed with args.
   In such case:

   1) Behaves like emplace except that the element is constructed as
   value_type(std::piecewise_construct,

              std::forward_as_tuple(k),

              std::forward_as_tuple(std::forward<Args>(args)...))
   2) Behaves like emplace except that the element is constructed as
   value_type(std::piecewise_construct,

              std::forward_as_tuple(std::move(k)),

              std::forward_as_tuple(std::forward<Args>(args)...))
   3) Behaves like emplace except that the element is constructed as
   value_type(std::piecewise_construct,

              std::forward_as_tuple(std::forward<K>(k)),

              std::forward_as_tuple(std::forward<Args>(args)...))
   4) Behaves like emplace_hint except that the element is constructed as
   value_type(std::piecewise_construct,

              std::forward_as_tuple(k),

              std::forward_as_tuple(std::forward<Args>(args)...))
   5) Behaves like emplace_hint except that the element is constructed as
   value_type(std::piecewise_construct,

              std::forward_as_tuple(std::move(k)),

              std::forward_as_tuple(std::forward<Args>(args)...))
   6) Behaves like emplace_hint except that the element is constructed as
   value_type(std::piecewise_construct,

              std::forward_as_tuple(std::forward<K>(k)),

              std::forward_as_tuple(std::forward<Args>(args)...))
   1-6) If value_type is not EmplaceConstructible into map from the corresponding
   expression, the behavior is undefined.
   3) This overload participates in overload resolution only if all following
   conditions are satisfied:
     * std::is_convertible_v<K&&, const_iterator> and std::is_convertible_v<K&&,
       iterator> are both false.
     * The qualified-id Compare::is_transparent is valid and denotes a type.
   If equal_range(u.first) == equal_range(k) is false, the behavior is undefined, where
   u is the new element to be inserted.
   6) This overload participates in overload resolution only if the qualified-id
   Compare::is_transparent is valid and denotes a type.
   If equal_range(u.first) == equal_range(k) is false, the behavior is undefined, where
   u is the new element to be inserted.

   No iterators or references are invalidated.

.SH Parameters

   k    - the key used both to look up and to insert if not found
   hint - iterator to the position before which the new element will be inserted
   args - arguments to forward to the constructor of the element

.SH Return value

   1-3) Same as for emplace.
   4-6) Same as for emplace_hint.

.SH Complexity

   1-3) Same as for emplace.
   4-6) Same as for emplace_hint.

.SH Notes

   Unlike insert or emplace, these functions do not move from rvalue arguments if the
   insertion does not happen, which makes it easy to manipulate maps whose values are
   move-only types, such as std::map<std::string, std::unique_ptr<foo>>. In addition,
   try_emplace treats the key and the arguments to the mapped_type separately, unlike
   emplace, which requires the arguments to construct a value_type (that is, a
   std::pair).

   Overloads (3,6) can be called without constructing an object of type Key.

               Feature-test macro                Value    Std            Feature
  __cpp_lib_map_try_emplace                     201411L \fI(C++17)\fP std::map::try_emplace,
                                                                std::map::insert_or_assign
                                                                Heterogeneous overloads
                                                                for the remaining member
  __cpp_lib_associative_heterogeneous_insertion 202311L (C++26) functions in ordered and
                                                                unordered associative
                                                                containers. Overloads \fB(3)\fP
                                                                and \fB(6)\fP.

.SH Example


// Run this code

 #include <iostream>
 #include <string>
 #include <map>
 #include <utility>

 void print_node(const auto& node)
 {
     std::cout << '[' << node.first << "] = " << node.second << '\\n';
 }

 void print_result(auto const& pair)
 {
     std::cout << (pair.second ? "inserted: " : "ignored:  ");
     print_node(*pair.first);
 }

 int main()
 {
     using namespace std::literals;
     std::map<std::string, std::string> m;

     print_result(m.try_emplace("a", "a"s));
     print_result(m.try_emplace("b", "abcd"));
     print_result(m.try_emplace("c", 10, 'c'));
     print_result(m.try_emplace("c", "Won't be inserted"));

     for (const auto& p : m)
         print_node(p);
 }

.SH Output:

 inserted: [a] = a
 inserted: [b] = abcd
 inserted: [c] = cccccccccc
 ignored:  [c] = cccccccccc
 [a] = a
 [b] = abcd
 [c] = cccccccccc

.SH See also

   emplace      constructs element in-place
   \fI(C++11)\fP      \fI(public member function)\fP
   emplace_hint constructs elements in-place using a hint
   \fI(C++11)\fP      \fI(public member function)\fP
                inserts elements
   insert       or nodes
                \fI(since C++17)\fP
                \fI(public member function)\fP
